home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 33 / Amiga Format AFCD33 (Issue 117, Dec 1998).iso / -seriously_amiga- / programming / c / rsrctracklib / docs / autodocs next >
Text File  |  1998-09-14  |  13KB  |  517 lines
  1.  
  2. $VER: Autodocs of ressourcetracking.library 37.0 (20.07.98)
  3.  
  4. (C) Copyright 1998 Patrick BURNAND
  5. All Rights Reserved.
  6.  
  7. Original code for the example.library done by Andreas R. Kleinert.
  8. See Clib37x.lha on Aminet !
  9.  
  10.  
  11. ===============================================================================
  12.  
  13.  
  14. ressourcetracking.library/rt_AddManager
  15.  
  16.  
  17. NAME
  18.     rt_AddManager  -  Sets up a ressource tracking stack for the calling task.
  19.  
  20.  
  21. SYNOPSIS
  22.     ULONG rt_AddManager (ULONG recNum)
  23.       D0                       D1
  24.  
  25.  
  26. FUNCTION
  27.     Adds a ressource tracking stack for the calling task.  This call must be
  28.     done before trying to allocate any system ressource using the
  29.     ressourcetracking.library.  
  30.  
  31.     It is safe to call this function several times for the same task.   If the
  32.     stack already exists rt_AddManager() always returns successfully.
  33.  
  34.     WARNING: the stack allocated using this function is strictly local the
  35.     calling task.  If your program is divided in several tasks, each one must
  36.     rt_AddManager() to get ressources using ressourcetracking.library.
  37.  
  38.  
  39. INPUTS
  40.     recNum:
  41.         Number of ressources tracking records to allocate.  (Number of elements
  42.         of the ressource tracking stack.)  Each record needs 16 bytes; it's not
  43.         dramatic if this number is to big.  The number you provide here must be
  44.         large enough or the stack will overflow and the system will probably
  45.         crash.
  46.  
  47.  
  48. RESULT
  49.     Non-zero if the stack has been successfully created, else zero.
  50.  
  51.  
  52. NOTE
  53.     If you don't know how to estimate the number of necessary records, you can
  54.     get the number of really used records using rt_FindNumUsed().
  55.  
  56.  
  57. BUGS
  58.     None known.
  59.  
  60.  
  61. SEE ALSO
  62.     rt_RemManager(), rt_FindNumUsed().
  63.  
  64.  
  65. TODO
  66.     Add the possibility to create several ressource tracking stacks per task.
  67.  
  68.  
  69. ===============================================================================
  70.  
  71.  
  72. ressourcetracking.library/rt_RemManager
  73.  
  74.  
  75. NAME
  76.     rt_RemManager  -  Frees ressources and deletes ressource tracking stack.
  77.  
  78.  
  79. SYNOPSIS
  80.     void rt_RemManager (void)
  81.  
  82.  
  83. FUNCTION
  84.     Closes or frees all the ressources remaining on the ressource tracking
  85.     stack and deletes the ressource tracking stack.  The ressources are freed
  86.     in the reverse order as the allocation.
  87.  
  88.     This function must be called before your program exits.  This is a good
  89.     idea to do an 'atexit(rt_RemManager)', so that your program can exit from
  90.     everywhere.
  91.  
  92.     rt_RemManager() and rt_AddManager() must be called by the same task.
  93.  
  94.     It is safe to call this function several times.  It is safe to call this
  95.     function even if rt_AddManager() didn't succeed.
  96.  
  97.  
  98. INPUTS
  99.  
  100.  
  101. RESULT
  102.  
  103.  
  104. BUGS
  105.     None known.
  106.  
  107.  
  108. SEE ALSO
  109.     rt_AddManager(), rt_SetMarker(), rt_UnsetMarker().
  110.  
  111.  
  112. ===============================================================================
  113.  
  114.  
  115. ressourcetracking.library/rt_SetMarker
  116.  
  117.  
  118. NAME
  119.     rt_SetMarker  -  Puts a marker onto the ressource tracking stack.
  120.  
  121.  
  122. SYNOPSIS
  123.     void rt_SetMarker (void)
  124.  
  125.  
  126. FUNCTION
  127.     Puts a marker onto the ressource tracking stack.  This marker is used to
  128.     remember a particular position in the stack.  When you call
  129.     rt_UnsetMarker(), all the ressources allocated since the last
  130.     rt_SetMarker() will be freed.
  131.     A marker is itself considered as a ressource and takes one ressource
  132.     tracking record.
  133.  
  134.     Usage example:  (rt_AddManager() has already been called)
  135.         /* ... do something ... */
  136.         myPort = rt_CreateMsgPort();
  137.         rt_SetMarker();     /* Puts a marker in this place. */
  138.         rt_SetCustomF0 ((APTR)myFunc);
  139.         rt_AllocMem (1024, MEMF_CLEAR);
  140.         rt_UnsetMarker();   /* Frees the block of memory and calls myFunc(). */
  141.                             /* But myPort is still valid since */
  142.                             /* CreateMsgPort() was called before the last */
  143.                             /* rt_SetMarker(). */
  144.  
  145. INPUTS
  146.  
  147.  
  148. RESULT
  149.  
  150.  
  151. NOTE
  152.     The calls to rt_SetMarker() and rt_UnsetMarker() can be nested.
  153.  
  154.  
  155. BUGS
  156.     None known.
  157.  
  158.  
  159. SEE ALSO
  160.     rt_UnsetMarker()
  161.  
  162.  
  163. ===============================================================================
  164.  
  165.  
  166. ressourcetracking.library/rt_UnsetMarker
  167.  
  168.  
  169. NAME
  170.     rt_UnsetMarker  -  Removes a marker out off the ressource tracking stack.
  171.  
  172.  
  173. SYNOPSIS
  174.     void rt_UnsetMarker (void)
  175.  
  176.  
  177. FUNCTION
  178.     Frees all the ressources allocated since the last call to rt_SetMarker() in
  179.     the reverse order of the allocation and then removes the marker.
  180.  
  181.     Usage example:  (rt_AddManager() has already been called)
  182.         /* ... do something ... */
  183.         myPort = rt_CreateMsgPort();
  184.         rt_SetMarker();     /* Puts a marker in this place. */
  185.         rt_SetCustomF0 ((APTR)myFunc);
  186.         rt_AllocMem (1024, MEMF_CLEAR);
  187.         rt_UnsetMarker();   /* Frees the block of memory and calls myFunc(). */
  188.                             /* But myPort is still valid since */
  189.                             /* CreateMsgPort() was called before the last */
  190.                             /* rt_SetMarker(). */
  191.  
  192. INPUTS
  193.  
  194.  
  195. RESULT
  196.  
  197.  
  198. NOTE
  199.     If you call rt_UnsetMarker() more times than you called rt_SetMarker(), all
  200.     the ressources will be freed but the ressource tracking stack will still 
  201.     exist.  (You must call rt_RemManager() at the end of your program anyway)
  202.  
  203.  
  204. BUGS
  205.     None known.
  206.  
  207.  
  208. SEE ALSO
  209.     rt_SetMarker()
  210.  
  211.  
  212. ===============================================================================
  213.  
  214.  
  215. ressourcetracking.library/rt_FindNumUsed
  216.  
  217.  
  218. NAME
  219.     rt_FindNumUsed  -  Finds the number of used ressource tracking records.
  220.  
  221.  
  222. SYNOPSIS
  223.     ULONG rt_FindNumUsed (void)
  224.       D0
  225.  
  226.  
  227. FUNCTION
  228.     Finds the number of used ressource tracking records.  It is useful not to
  229.     waste to much memory when you do an rt_AddManager().  This function only
  230.     returns a meaningfull number when it's called just before rt_RemManager().
  231.  
  232.     It can be used for debugging purposes too.  If you do allocation in a loop
  233.     and suspect a problem.
  234.  
  235.     Usage example:
  236.         /* ... prepare to quit ... */
  237.         #ifdef DEBUG
  238.         printf ("Number of used records: %ld\n", rt_FindNumUsed());
  239.         #endif
  240.         rt_RemManager();
  241.  
  242.  
  243.  
  244. INPUTS
  245.  
  246.  
  247. RESULT
  248.  
  249.  
  250. BUGS
  251.     None known.
  252.  
  253.  
  254. SEE ALSO
  255.     rt_AddManager()
  256.  
  257.  
  258. ===============================================================================
  259.  
  260.  
  261. ressourcetracking.library/rt_SetCustomF0
  262.  
  263.  
  264. NAME
  265.     rt_SetCustomF0  -  Calls a function when ressources are freed.
  266.  
  267.  
  268. SYNOPSIS
  269.     void rt_SetCustomF0 (APTR func)
  270.                              D1
  271.  
  272.  
  273. FUNCTION
  274.     Adds the adress of a function on the ressource tracking stack.  The
  275.     function you pass the adress of will be called when ressources are freed,
  276.     i.e. when you call rt_UnsetMarker() or rt_RemManager().
  277.  
  278.     This mechanism is typically used to have custom (more sophisticated)
  279.     liberation function or to do ressource tracking on ressources not supported
  280.     by the ressource tracking library  (on not supported shared libraries).
  281.  
  282.     The function you pass to rt_SetCustomF0() must be parameter-less.  You must
  283.     use rt_SetCustomF1() or rt_SetCustomF2() to pass function which take 1 or 2
  284.     parameters.
  285.  
  286.     Usage example:
  287.         rt_SetMarker();
  288.         rt_SetCustomF0 ((APTR)myFunc);  /* Pass the adress of your function */
  289.         rt_AllocMem (1024, MEMF_CLEAR);
  290.         rt_UnsetMarker();   /* Frees the block of memory and calls myFunc(). */
  291.  
  292.     rt_SetCustomF0 takes 1 ressource tracking record.
  293.  
  294.  
  295. INPUTS
  296.     func:
  297.         Address of a parameter-less function.  Note that any return value of
  298.         your function will be ignored.
  299.  
  300.  
  301. RESULT
  302.  
  303.  
  304. BUGS
  305.     None known.
  306.  
  307.  
  308. SEE ALSO
  309.     rt_SetCustomF1(), rt_SetCustomF2()
  310.  
  311.  
  312. ===============================================================================
  313.  
  314.  
  315. ressourcetracking.library/rt_SetCustomF1
  316.  
  317.  
  318. NAME
  319.     rt_SetCustomF1  -  Calls a function when ressources are freed.
  320.  
  321.  
  322. SYNOPSIS
  323.     void rt_SetCustomF1 (APTR func, ULONG arg1)
  324.                              D1         D2
  325.  
  326.  
  327. FUNCTION
  328.     This function is the same as rt_SetCustomF0() except that the function you
  329.     pass must have 1 parameter. When ressources are freed, your function will
  330.     be called with the parameter arg1.
  331.  
  332.     See the docs of rt_SetCustomF0().
  333.  
  334.     Usage example:
  335.         rt_SetMarker();
  336.         rt_SetCustomF1 ((APTR)myFunc, myParam); /* Pass the adress of your */
  337.                                                 /* function and myParam. */
  338.         rt_AllocMem (1024, MEMF_CLEAR);
  339.         rt_UnsetMarker();   /* Frees the block of memory */
  340.                             /* and do a myFunc(myParam). */
  341.  
  342.  
  343. INPUTS
  344.     func:
  345.         Address of a function taking 1 parameter.  Note that any return value
  346.         of your function will be ignored.
  347.     arg1:
  348.         The value to pass to your function as a parameter.
  349.  
  350.  
  351. RESULT
  352.  
  353.  
  354. NOTE
  355.     How your function will get the parameter arg1 may depend of your compiler.
  356.     Perhaps you won't even be able to use rt_SetCustomF1() or rt_SetCustomF2()
  357.     if the way the parameters of the functions are passed are not compatible.
  358.     Anyway you should make some tests before using rt_SetCustomF1() or
  359.     rt_SetCustomF2().
  360.  
  361.  
  362. BUGS
  363.     None known.
  364.  
  365.  
  366. SEE ALSO
  367.     rt_SetCustomF0(), rt_SetCustomF2()
  368.  
  369.  
  370. ===============================================================================
  371.  
  372.  
  373. ressourcetracking.library/rt_SetCustomF2
  374.  
  375.  
  376. NAME
  377.     rt_SetCustomF2  -  Calls a function when ressources are freed.
  378.  
  379.  
  380. SYNOPSIS
  381.     void rt_SetCustomF2 (APTR func, ULONG arg1, ULONG arg2)
  382.                              D1         D2          D3
  383.  
  384.  
  385. FUNCTION
  386.     This function is the same as rt_SetCustomF0() except that the function you
  387.     pass must have 2 parameters. When ressources are freed, your function will
  388.     be called with the parameters arg1 and arg2.
  389.  
  390.     See the docs of rt_SetCustomF0().
  391.  
  392.     Usage example:
  393.         rt_SetMarker();
  394.         rt_SetCustomF2 ((APTR)myFunc, 
  395.                         myParam1, myParam2); /* Pass the adress of your */
  396.                                              /* function and myParam1 and */
  397.                                              /* myParam2. */
  398.         rt_AllocMem (1024, MEMF_CLEAR);
  399.         rt_UnsetMarker();   /* Frees the block of memory and do */
  400.                             /* a myFunc(myParam1, myParam2). */
  401.  
  402.  
  403. INPUTS
  404.     func:
  405.         Address of a function taking 2 parameters.  Note that any return value
  406.         of your function will be ignored.
  407.     arg1:
  408.         The value to pass to your function as the first of the two parameters.
  409.     arg2:
  410.         The value to pass to your function as the second of the two parameters.
  411.  
  412.  
  413. RESULT
  414.  
  415.  
  416. NOTE
  417.     How your function will get the parameter arg1 may depend of your compiler.
  418.     Perhaps you won't even be able to use this rt_SetCustomF1() or
  419.     rt_SetCustomF2() if the way the parameters of the functions are passed
  420.     are not compatible.
  421.     It is even possible that the order of the two parameters is wrong.  
  422.     (i.e. arg1, arg2 becomes arg2, arg1.)
  423.     Anyway you should make some tests before using rt_SetCustomF1() or
  424.     rt_SetCustomF2().
  425.  
  426.  
  427. BUGS
  428.     None known.
  429.  
  430.  
  431. SEE ALSO
  432.     rt_SetCustomF0(), rt_SetCustomF1()
  433.  
  434.  
  435. ===============================================================================
  436.  
  437.  
  438. ressourcetracking.library/rt_AllocMem
  439. ressourcetracking.library/rt_AllocSignal
  440. ressourcetracking.library/rt_OpenLibrary
  441. ressourcetracking.library/rt_AddSemaphore
  442. ressourcetracking.library/rt_Forbid
  443. ressourcetracking.library/rt_AllocTrap
  444. ressourcetracking.library/rt_CreateMsgPort
  445. ressourcetracking.library/rt_AddPort
  446.  
  447.  
  448.  
  449.  
  450. NAME
  451.     rt_AllocMem  -  Allocates memory given certain requirements.
  452.     rt_AllocSignal  -  Allocates a signal.
  453.     rt_OpenLibrary  -  Opens an Amiga shared library.
  454.     rt_AddSemaphore  -  Adds a semaphore.
  455.     rt_Forbid  -  Disable multitasking.
  456.     rt_AllocTrap  -  Allocates a trap.
  457.     rt_CreateMsgPort  -  Creates a new message port.
  458.     rt_AddPort  -  Adds a port the public port list.
  459.  
  460.  
  461.  
  462. SYNOPSIS
  463.     APTR rt_AllocMem (ULONG byteSize, ULONG requirements)
  464.      D0                     D1                D2
  465.  
  466.     BYTE rt_AllocSignal (ULONG signalNum)
  467.      D0                        D1
  468.  
  469.     struct Library * rt_OpenLibrary (UBYTE *libName, ULONG version)
  470.           D0                               D1             D2
  471.  
  472.     void rt_AddSemaphore (struct SignalSemaphore *sigSem)
  473.                                         D1
  474.     void rt_Forbid (void)
  475.  
  476.     ULONG rt_AllocTrap (ULONG trapNum)
  477.       D0                     D1
  478.  
  479.     struct MsgPort * rt_CreateMsgPort (void)
  480.           D0
  481.  
  482.     void rt_AddPort (struct MsgPort *port)
  483.                              D1
  484.  
  485.  
  486. FUNCTION
  487.     These functions performs exactly the same task as the corresponding ones in
  488.     AmigaOS.  The only difference is that each one creates a ressource tracking
  489.     record and that it is forbidden to call the «reverse» function.  (i.e. it's
  490.     forbidden to call FreeMem after an rt_AllocMem.)  But you can go through
  491.     the ressource tracking stack using rt_SetMarker() and rt_UnsetMarker().
  492.  
  493.     See the documentation of AmigaOS.
  494.  
  495.  
  496. INPUTS
  497.     See the documentation of AmigaOS.
  498.  
  499.  
  500. RESULT
  501.     See the documentation of AmigaOS.
  502.  
  503.  
  504. NOTE
  505.     Assembly programmers must note that register specification isen't the same
  506.     as in the AmigaOS.
  507.  
  508.  
  509. BUGS
  510.     None known.
  511.  
  512.  
  513. SEE ALSO
  514.     Documentation of AmigaOS
  515.  
  516.  
  517.